---
title: Getting Started with Nextjs
description: A guide for installing Chakra UI with Nextjs projects
tags: ['nextjs']
author: estheragbaje
category: frameworks
---

<Box mt={3}>
  <AspectRatio ratio={16 / 8.84}>
    <VideoPlayer
      width='100%'
      height='100%'
      url='https://www.youtube.com/watch?v=wI2vqXsjsIo'
      config={{
        youtube: {
          playerVars: {
            controls: true,
          },
        },
      }}
    />
  </AspectRatio>
</Box>

### Installation

In your Next.js project, install Chakra UI by running either of the following:

```bash
npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^6
```

```bash
yarn add @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^6
```

### Provider Setup

After installing Chakra UI, you need to set up the `ChakraProvider` at the root
of your application.

Go to `pages/_app.js` or `pages/_app.tsx` (create it if it doesn't exist) and
wrap the `Component` with the `ChakraProvider`:

```jsx live=false
// pages/_app.js
import { ChakraProvider } from '@chakra-ui/react'

function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider>
      <Component {...pageProps} />
    </ChakraProvider>
  )
}

export default MyApp
```

### Customizing theme

If you intend to customise the default theme object to match your design
requirements, you need to extend the `theme`.

Chakra UI provides an `extendTheme` function that deep merges the default theme
with your customizations.

```jsx live=false
// pages/_app.js
import { ChakraProvider } from '@chakra-ui/react'

// 1. Import the extendTheme function
import { extendTheme } from '@chakra-ui/react'

// 2. Extend the theme to include custom colors, fonts, etc
const colors = {
  brand: {
    900: '#1a365d',
    800: '#153e75',
    700: '#2a69ac',
  },
}

const theme = extendTheme({ colors })

// 3. Pass the `theme` prop to the `ChakraProvider`
function MyApp({ Component, pageProps }) {
  return (
    <ChakraProvider theme={theme}>
      <Component {...pageProps} />
    </ChakraProvider>
  )
}

export default MyApp;
```

> To further customize components or build your own design system, the
> `theme-tools` package includes useful utilities.

### Color Mode Script

The color mode script needs to be added before the content inside the `body` tag
for local storage syncing to work correctly.

> When setting the initial color mode, we recommend adding it as a config to
> your theme and reference that in the `ColorModeScript`.

> To use `ColorModeScript` on a site with strict `Content-Security-Policy`, you
> can use the `nonce` prop that will be passed to the `<script>` tag.

```jsx live=false ln={14}
// pages/_document.js

import { ColorModeScript } from '@chakra-ui/react'
import NextDocument, { Html, Head, Main, NextScript } from 'next/document'
import theme from './theme'

export default class Document extends NextDocument {
  render() {
    return (
      <Html lang='en'>
        <Head />
        <body>
          {/* 👇 Here's the script */}
          <ColorModeScript initialColorMode={theme.config.initialColorMode} />
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}
```

#### Notes on TypeScript 🚨

Please note that when adding Chakra UI to a TypeScript project, a minimum
TypeScript version of `4.1.0` is required.

### ChakraProvider Props

| Name             | Type             | Default               | Description                                         |
| ---------------- | ---------------- | --------------------- | --------------------------------------------------- |
| resetCSS         | `boolean`        | `true`                | automatically includes `<CSSReset />`               |
| theme            | `Theme`          | `@chakra-ui/theme`    | optional custom theme                               |
| colorModeManager | `StorageManager` | `localStorageManager` | manager to persist a users color mode preference in |
| portalZIndex     | `number`         | `undefined`           | common z-index to use for `Portal`                  |
